.\" $Id: PAPI_attach.3,v 1.1.2.1 2006/10/26 20:35:07 terpstra Exp $
.TH PAPI_attach 3 "October, 2006" "PAPI Programmer's Reference" "PAPI"

.SH NAME
.nf
PAPI_attach  \- attach PAPI event set to the specified thread id
PAPI_detach  \- detach PAPI event set from previously specified thread id and restore to executing thread
.fi

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int\ PAPI_attach(int " EventSet ", unsigned long " tid ");"
.BI "int\ PAPI_detach(int " EventSet ");"
.fi
.B Fortran Interface
.nf
.B <none>
.fi

.SH DESCRIPTION
.B PAPI_attach()
and
.B PAPI_detach()
are wrapper functions that access
.BR "PAPI_set_opt() (3)" " to allow PAPI to monitor performance counts"
on a thread other than the one currently executing. This is sometimes referred to as third party monitoring.
.B PAPI_attach()
connects the specified EventSet to the specifed thread;
.B PAPI_detach()
breaks that connection and restores the EventSet to the original executing thread.

.SH ARGUMENTS
.I EventSet
--  an integer handle for a PAPI Event Set as created by
.BR "PAPI_create_eventset" (3)
.LP
.I tid
-- a thread id as obtained from, for example,
.BR "PAPI_list_threads" "(3) or "
.BR "PAPI_thread_id" "(3)."

.SH RETURN VALUES
On success, these functions return
.B "PAPI_OK." 
On error, a negative error code is returned.

.SH ERRORS
.TP
.B "PAPI_ESBSTR"
This feature is unsupported on this substrate.
.TP
.B "PAPI_EINVAL"
One or more of the arguments is invalid.
.TP
.B "PAPI_ENOEVST"
The event set specified does not exist.
.TP
.B "PAPI_EISRUN"
The event set is currently counting events.


.SH EXAMPLES
.nf
.if t .ft CW
int EventSet = PAPI_NULL;
unsigned long pid;

pid = fork();
if (pid <= 0)
  exit(1);
	
if (PAPI_create_eventset(&EventSet) != PAPI_OK)
  exit(1);

/* Add Total Instructions Executed to our EventSet */

if (PAPI_add_event(EventSet, PAPI_TOT_INS) != PAPI_OK)
  exit(1);

/* Attach this EventSet to the forked process */

if (PAPI_attach(EventSet, pid) != PAPI_OK)
  exit(1);


.if t .ft P
.fi

.SH BUGS
There are no known bugs in these functions.

.SH SEE ALSO
.BR PAPI_list_threads "(3), " PAPI_thread_id "(3), " PAPI_thread_init "(3), "
.BR PAPI_set_opt "(3)" 
